PyVistaとSphinx#
PyVistaを活用して，素晴らしいインタラクティブなWebドキュメントを作成することができます．
ちなみに
このチュートリアルのセクションは，PyVistaドキュメントの Plotting Themes と Sphinx PyVista Plot Directive の章から採用されたものです．
ドキュメントに3Dプロットを動的に生成する#
PyVistaを使うと， Matplotlib plot_directive と同じように，Sphinx内で静的または動的な画像を直接生成することができます．手動でプロットを作成して，コードセクションの後に追加するのではなく，代わりに動的に画像を生成して，ドキュメントの中に直接埋め込むことができるのです．これは sphinx-gallery ともシームレスに動作しますので， Matplotlib Example Gallery のようなノートブックのサンプルを作成することができます．
さらに副次的な利点として，生成したドキュメントがプロジェクトの API と一致することを確認できます．これを GitHub ワークフロー に組み込むと，次のようになります．
このセクションでは，以下の項目について説明します．
静的プロット - Sphinx PyVista プロットディレクティブ#
Sphinxを使用してドキュメントをビルドする際に， conf.py に以下を追加すると， pyvista-plot ディレクティブを使用して，sphinx内でPyVistaプロットの静止画像を生成することができます．
extensions = [
"sphinx.ext.napoleon",
"pyvista.ext.plot_directive",
]
そうすれば，sphinxのドキュメントファイルの中で，plottingディレクティブを発行することができます:
.. pyvista-plot::
:caption: A sphere
:include-source: True
>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> out = sphere.plot()
以下のように表示されます．
>>> import pyvista
>>> sphere = pyvista.Sphere()
>>> out = sphere.plot()
これはデフォルトの球体#
Jupyter Sphinx拡張を使った動的プロッティング#
PyVistaは jupyter-sphinx 拡張もサポートしています．この拡張機能を使うと， jupyter-execute ディレクティブを使って，sphinx *.rst ファイル内のコードブロックを実行することができます:
.. jupyter-execute::
name = 'world'
print('hello ' + name + '!')
以下のように表示されます:
name = 'world'
print('hello ' + name + '!')
hello world!
同様に，通常ノートブック内でレンダリングされるPyVistaからの出力は， jupyter-execute ディレクティブの出力セルにレンダリングされます．例えば， pythreejs バックエンドを使用したプロットは次のようになります．
.. jupyter-execute::
from pyvista import examples
dataset = examples.download_urn()
dataset.plot(color='tan', jupyter_backend='pythreejs', window_size=(700, 400))
以下のように表示されます:
from pyvista import examples
dataset = examples.download_urn()
dataset.plot(color='tan', jupyter_backend='pythreejs', window_size=(700, 400))
PyVistaで Panel バックエンドを使用する#
PyVistaは vtk.js jupyterlab plotting backendとして panel <https://github.com/holoviz/panel>`_ libraryの使用をサポートしています．このライブラリは，スタンドアロンのVTKビューアとして，あるいは緊密に連携した ``pyvista plotting backendとして使用することが可能です． 例えば，Jupyterノートブック環境では， plot や Plotter.show に jupyter_backend='panel' を渡すと，自動的にJuptyerと panel でプロットできるようになります．
例えば，これは PyVista のロゴです:
.. jupyter-execute::
from pyvista import demos
demos.plot_logo(background='white', jupyter_backend='panel')
以下のようにドキュメント内に表示されています:
from pyvista import demos
demos.plot_logo(background='white', jupyter_backend='panel')
使用例と使用方法#
Jupyterノートブック内で panel を使用するには2つの方法があります． mesh.plot() で jupyter_backend を設定することにより，プロットごとに使用することができます．
.. jupyter-execute::
import pyvista as pv
from pyvista import examples
# create a point cloud from lidar data and add height scalars
dataset = examples.download_lidar()
point_cloud = pv.PolyData(dataset.points[::100])
point_cloud['height'] = point_cloud.points[:, 2]
point_cloud.plot(window_size=[500, 500],
jupyter_backend='panel',
cmap='jet',
point_size=2,
background='w')
そして，これがSphinxでの出力結果です:
import pyvista as pv
from pyvista import examples
# create a point cloud from lidar data and add height scalars
dataset = examples.download_lidar()
point_cloud = pv.PolyData(dataset.points[::100])
point_cloud['height'] = point_cloud.points[:, 2]
point_cloud.plot(window_size=[500, 500],
jupyter_backend='panel',
cmap='jet',
point_size=2,
background='w')
または，プロットバックエンドとグローバルテーマを設定するコードを最初に隠すことができます:
.. jupyter-execute::
:hide-code:
import pyvista as pv
# Set the global jupyterlab backend. All plots from this point
# onward will use the ``panel`` backend and do not have to be
# specified in ``show``
pv.set_jupyter_backend('panel')
そして，任意のデータセットに対して plot を直接実行するようにします:
.. jupyter-execute::
from pyvista import examples
dataset = examples.download_dragon()
dataset.plot(cpos="xy")
以下のように見えます:
from pyvista import examples
dataset = examples.download_dragon()
dataset.plot(cpos="xy")